<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Anatomy of an ArduinoUnit Sketch - ArduinoUnit Documentation</title>
<link href="styles/styles.css" type="text/css" rel="stylesheet"/>
</head>
<body>
<h1><a href="index.html"><img border="0" src="images/arduinounit.png"/></a> <span class="success">Arduino</span><span class="failure">Unit</span> Documentation</h1>

<h2>Anatomy of an ArduinoUnit Sketch</h2>
<p>
The following example sketch will be used to demonstrate the individual parts
of an ArduinoUnit sketch.
</p>
<code>
#include &lt;ArduinoUnit.h&gt;

TestSuite suite;

void setup() {
}

test(addition) {
  assertTrue(2 == 1 + 1);
}

test(subtraction) {
  assertEquals(1, 3 - 2);
}

void loop() {
  suite.run();
}
</code>

<h3>ArduinoUnit Library Import</h3>
<p>
To use ArduinoUnit you must import the library. You can do this within the
Arduino IDE by clicking Sketch | Import Library | ArduinoUnit which inserts
the following code at the top of your sketch:
</p>
<code>
#include &lt;ArduinoUnit.h&gt;
</code>

<h3>TestSuite Creation</h3>
<p>
An ArduinoUnit sketch consists of a test suite containing one or more tests.
To create a test declare a variable of type <code>TestSuite</code> outside
of all functions:
</p>
<code>
TestSuite suite;
</code>

<h3>Test Functions</h3>
<p>
To add a test to the test suite, simply surround the name of the test with
<code>test()</code> and follow it with the test code within curly braces. In
this example two tests are created; one called <code>addition</code> the other
<code>subtraction</code>.
</p>
<code>
test(addition) {
  // ...
}

test(subtraction) {
  // ...
}
</code>

<h3>Assertions</h3>
<p>
A test consists of (up to) three parts:
<ol>
  <li>Initialization</li>
  <li>Assertions</li>
  <li>Clean up</li>
</ol>
The initialization and clean up code are optional and depend on what is being
tested. However, one or more assertions or checking code must exist for the
test to actually test something. If all assertions within a test succeed, the
test succeeds. If any assertions within a test fail, the test fails.
</p>
<p>
Two types of assertion are available, the boolean assertion,
<code>assertTrue</code> which checks that a value is <code>true</code> and the
equality assertion, <code>assertEquals</code> which checks that two integers
are equal. Additional custom assertion functions can be built from these two
functions if necessary.
</p>
<h4>Boolean Assertion</h4>
<p>
A boolean assertion checks that a value is <code>true</code>. If the value is
not <code>true</code> the assertion fails and its enclosing test also fails.
In this example the assertion is checking that <code>2 == 1 + 1</code>
evaluates to <code>true</code> which it will except in the case of extreme
hardware failure.
</p>
<code>
assertTrue(2 == 1 + 1);
</code>
<h4>Equality Assertion</h4>
<p>
An equality assertion checks that two values are equal. The order of the
arguments is important, with the expected value being passed as the first
argument and the actual value as the second. In this example the
value of <code>3 - 2</code> is checked against the expected value,
<code>1</code>.
</p>
<p>
Note that the current implementation only supports checking equality of
integer arguments.
</p>
<code>
assertEquals(1, 3 - 2);
</code>

<h3>TestSuite Execution</h3>
<p>
The TestSuite is run by calling its <code>run()</code> function. You'll
generally want to do this within the standard <code>loop()</code> function.
Although called within <code>loop()</code>, the implementation of
<code>run()</code> ensures that the tests are run and their results reported
only once.
</p>
<code>
void loop() {
  suite.run();
}
</code>

</body>
</html>